Application configuration reference

You can configure your Kanzi application:

While you can configure your Kanzi application in the onConfigure() function, in application.cfg you can configure some parameters without recompiling your application or even without a C++ application. The configuration you specify in application.cfg overrides the configuration you specify in onConfigure().

For example, in application.cfg you can tell your Kanzi application which kzb file to load, enable performance information in your application, and set how many threads you want to use for loading the application resources.

See Configuring your application.

You can use these application configuration settings.

Loading
  BinaryName
ModuleNames
LoadingThreadCount
MaxPendingResources

Performance
  ApplicationIdleState
MaximumFPS
PerformanceInfoLevel
PerformanceInfoPosition
ProfilingCategoryFilter
MainLoopProfilingSampleBufferCount

Glyph cache texture size
  GlyphCacheHeight
GlyphCacheWidth

Optimization
  Graphics initialization

Graphics card selection
 

DeviceIdentifier

Graphics performance logging
  GraphicsLoggingEnabled
LogOpenGLExtensions
LogOpenGLInformation
LogSurfaceInformation

Graphics library
  GraphicsBackend
contextAPI

Surface properties
  SurfaceBitsStencil
SurfaceBitsDepthBuffer
SurfaceBitsRed
SurfaceBitsGreen
SurfaceBitsBlue
SurfaceBitsAlpha
SurfaceBitsPadding
SurfaceSamplesAntialiasing
SwapBehavior
Application window position and size
  WindowX
WindowY
WindowWidth
WindowHeight
WindowOrder

Application window configuration
  WindowStyle
  DefaultDisplayIndex
  WindowBufferCount

Input handling
  InputTransform
InputTranslation
InputDiscardPointer
InputDiscardTouch

Input event devices on Linux
  InputEventDevice

Loading

BinaryName

You can set which kzb file or configuration file your Kanzi application loads when you launch your Kanzi application.

See Using kzb files.

In application.cfg BinaryName = "name"
In onConfigure() configuration.binaryName = "name";
Value
name Path to a single kzb file, or to the binary configuration file listing all kzb files that your Kanzi application loads.
application.cfg example

# Loads the kzb file named MyApplication.kzb.
BinaryName = "MyApplication.kzb"

# Loads the binary configuration file MyApplicationKzbs.cfg that lists
# all kzb files that your Kanzi application loads.
BinaryName = "MyApplication.kzb.cfg"

onConfigure() example

// Loads kzb file named MyApplication.kzb.
configuration.binaryName = "MyApplication.kzb";

// Loads the binary configuration file MyApplicationKzbs.cfg that lists
// all kzb files that your Kanzi application loads.
configuration.binaryName = "MyApplication.kzb.cfg";

ModuleNames

You can set which plugins your Kanzi application loads when you launch your Kanzi application.

In application.cfg ModuleNames= "names"
In onConfigure() configuration.moduleNames = names;
Values
names List of plugins to load.
application.cfg example

# Loads the plugin DLL files MyPlugin1.dll and MyPlugin2.dll.
ModuleNames = "MyPlugin1; MyPlugin1"

onConfigure() example
// Loads the plugin DLL files MyPlugin1.dll and MyPlugin2.dll. 
configuration.moduleNames = {"MyPlugin1", "MyPlugin1"};

LoadingThreadCount

When users run your Kanzi application in an environment with a multi-core processor, Kanzi automatically uses multiple CPU cores to load the GPU resources in the kzb files to RAM. See Loading resources in parallel.

GPU resources Kanzi loads in parallel include all types of textures, shaders, and meshes. To deploy these resources from RAM to GPU memory and to load prefab templates, Kanzi always uses the main thread. See Images and textures best practices, Shaders best practices, Meshes best practices.

In application.cfg LoadingThreadCount = threads
In onConfigure() configuration.loadingThreadCount = threads;
Values
threads Number of CPU cores used for loading the resources. The default value is 3.
application.cfg example
# Switches off the use of multiple cores for loading your application.
# Loads your application resources using the main thread.
LoadingThreadCount = 0
# Uses six threads to load your application.
LoadingThreadCount = 5
onConfigure() example
// Switches off the use of multiple cores for loading your application.
// Loads your application resources using the main thread.
configuration.loadingThreadCount = 0;
// Uses six threads to load your application.
configuration.loadingThreadCount = 5;

MaxPendingResources

You can set the maximum number of resources that the loading threads process at the same time. By increasing the number of resources you can speed up the loading, but at the same time you increase the peak memory use during loading because you can load more resources to the memory before they are deployed to the GPU.

In application.cfg MaxPendingResources = resources
In onConfigure() configuration.maxPendingResources = resources;
Values
resources The maximum number of resources processed at the same time by the loading threads. The default value is 0 and sets the maximum number of resources to the number of loading threads +1.
application.cfg example
# Sets the maximum number of resources processed by the loading
# threads to the number of loading threads + 1. This is the default value.
MaxPendingResources = 0
# Sets the maximum number of resources processed by the loading
# threads to 20 resources.
MaxPendingResources = 20
onConfigure() example
// Sets the maximum number of resources processed by the loading
// threads to the number of loading threads + 1. This is the default value.
configuration.maxPendingResources = 0;
// Sets the maximum number of resources processed by the loading
// threads to 20 resources.
configuration.maxPendingResources = 20;

Performance

ApplicationIdleState

Kanzi suspends the main loop when there is no input, tasks, timers, animations, or when there is nothing in the application that updates the rendering. See Application idle state.

When using application idle state, consider these use cases:

In application.cfg ApplicationIdleState = value
In onConfigure() configuration.applicationIdleStateEnabled = value;
Values
0 Disable the application idle state.
1 Enable the application idle state. Default value.
application.cfg example
# Disables the application idle state.
ApplicationIdleState = 0
onConfigure() example
// Disables the application idle state.
configuration.applicationIdleStateEnabled = 0;

MaximumFPS

You can limit the number of frames rendered per second by setting the maximum frame rate.

If your Kanzi application is showing an animation, Kanzi by default throttles the CPU to the maximum FPS. If there are no animations, Kanzi sets the application to idle state. For this reason to conserve the CPU and power, Kanzi by default limits the maximum frame rate to 60 frames per second. Use the application configuration to set the maximum frame rate for your application.

See PerformanceInfoLevel.

In application.cfg MaximumFPS = limit
In onConfigure() configuration.frameRateLimit = limit;
Value
limit The maximum frame rate of the application in frames per second.
application.cfg example
# Sets the maximum application frame rate to 32 frames per second.
MaximumFPS = 32
# Disables the limit.
MaximumFPS = 0
onConfigure() example
// Sets the maximum application frame rate to 32 frames per second.
configuration.frameRateLimit = 32;
// Disables the limit.
configuration.frameRateLimit = 0;

PerformanceInfoLevel

You can enable the display of Performance HUD that shows the performance information for your Kanzi application. Use the Performance HUD to see how your application performs on target devices and to find performance bottlenecks.

Performance HUD shows this performance information for your Kanzi application:

You can set the position of the Performance HUD inside the window of your Kanzi application. See PerformanceInfoPosition.

See Best practices.

In application.cfg PerformanceInfoLevel = level
In onConfigure() configuration.performanceInfoLevel = ApplicationProperties::level;
Values
level

The level of display of performance information.

To disable the display of the Performance HUD:

  • In application.cfg use 0. Default value.
  • In onConfigure() use PerformanceInfoLevelDisabled. Default value.

To enable the display of the frames rendered per second (FPS):

  • In application.cfg use 1.
  • In onConfigure() use PerformanceInfoLevelFPS.

To enable the display of the full Performance HUD:

  • In application.cfg use 2.
  • In onConfigure() use PerformanceInfoLevelFull.
application.cfg example
# Enables the full Performance HUD in a Kanzi application.
PerformanceInfoLevel = 2
onConfigure() example
// Enables the full Performance HUD in a Kanzi application.
configuration.performanceInfoLevel = ApplicationProperties::PerformanceInfoLevelFull;

PerformanceInfoPosition

You can set the position of the Performance HUD inside the window of your Kanzi application. To see the Performance HUD in the window of your Kanzi application, you must enable it. See PerformanceInfoLevel.

In application.cfg PerformanceInfoPositionX = positionX
PerformanceInfoPositionY = positionY
In onConfigure() configuration.performanceInfoProperties.positionX = positionX;
configuration.performanceInfoProperties.positionY = positionY;
Value
positionX Horizontal position of the top-left corner of the Performance HUD from the top-left corner of a Kanzi application window. Use 0 to position the Performance HUD to the left of the window.
positionY Vertical position of the top-left corner of the Performance HUD from the top-left corner of a Kanzi application window. Use 0 to position the Performance HUD to the top of the window.
application.cfg example
# Position the Performance HUD 100 pixels from the left side and  
# 20 pixels from the top of the Kanzi application window.
PerformanceInfoPositionX = 100
PerformanceInfoPositionY = 20
onConfigure() example
// Position the Performance HUD 100 pixels from the left side and
// 20 pixels from the top of the Kanzi application window.
configuration.performanceInfoProperties.positionX = 100;
configuration.performanceInfoProperties.positionY = 20;

ProfilingCategoryFilter

You can control the state of performance profiling categories that you use to group performance profilers, and set which profilers you want to show in the Performance HUD. See Measuring application performance.

In application.cfg ProfilingCategoryFilter = "category=state"
In onConfigure() configuration.profilingCategoryFilter = "category=state";
Values
category

The names of one or more profiling categories separated by pipes (|).
To set the state of all categories, use asterisk (*).

state
off Disable performance profiling category.
on Enable performance profiling category.
show Enable performance profiling category and show the graph in the Performance HUD.
To use this state, enable the full Performance HUD. See PerformanceInfoLevel.
You can use this state to profile the performance of tasks that happen in the Kanzi main loop.
See Showing performance measurement graphs in the Performance HUD and Measuring the performance of custom main loop tasks.

Separate a list of category-state pairs with semicolons (;).

application.cfg examples
# Enables the full Performance HUD.
PerformanceInfoLevel = 2
# Enables performance profiling for animations running in the main loop and shows the performance graph in the Performance HUD.
ProfilingCategoryFilter="MainLoopAnimation=show"
# Enables the MyFunctionProfiler category and disables the MainLoopRendering category.
ProfilingCategoryFilter="MyFunctionProfiler=on;MainLoopRendering=off"
# Enables all performance profiling categories.
ProfilingCategoryFilter="*=on"
# Enables categories Generic and MyProfilingCategory.
ProfilingCategoryFilter="Generic|MyProfilingCategory=on"
# Enables resource profiling. See Measuring the loading and deployment time of resources.
ProfilingCategoryFilter="ResourceLoading=on"
onConfigure() examples
// Enables the full Performance HUD.
configuration.performanceInfoLevel = ApplicationProperties::PerformanceInfoLevelFull;
// Enables performance profiling for animations running in the main loop and shows the performance graph in the Performance HUD.
configuration.profilingCategoryFilter = "MainLoopAnimation=show";
# Enables the MyFunctionProfiler category and disables the MainLoopRendering category.
configuration.profilingCategoryFilter="MyFunctionProfiler=on;MainLoopRendering=off"
// Enables all performance profiling categories.
configuration.profilingCategoryFilter = "*=on";
// Enables categories Generic and MyProfilingCategory.
configuration.profilingCategoryFilter = "Generic|MyProfilingCategory=on";
// Enables resource profiling. See Measuring the loading and deployment time of resources.
configuration.profilingCategoryFilter = "ResourceLoading=on";

This table lists the Kanzi startup performance profiling categories and profilers that are included in the Profiling build.

CategoryConfiguration nameProfiler
Application initializationStartupInitializationm_initializationProfiler
Default resource registrationStartupRegisterDefaultResourcesm_registerDefaultResourcesProfiler
Graphics initializationStartupInitializeGraphicsm_initializeGraphicsProfiler
GL subsystem initializationStartupInitializeGLm_initializeGLProfiler
Startup kzb file openingStartupOpenKzbm_openKzbProfiler
Loading threads initialization StartupInitializeLoadingThreadsm_initializeLoadingThreadsProfiler
Metadata registrationStartupRegisterMetadatam_registerMetadataProfiler
Plugins loadingStartupLoadPluginsm_loadPluginsProfiler
Prefabs loadingStartupLoadPrefabm_loadPrefabProfiler
Prefabs instantiationStartupInstantiatePrefabm_instantiatePrefabProfiler
Prefabs attachmentStartupAttachPrefabm_attachPrefabProfiler
Renderer resetStartupResetRendererm_resetRendererProfiler
Runtime assets registrationStartupRegisterRuntimeAssetsm_registerRuntimeAssetsProfiler
   

This table lists the Kanzi main loop task performance profiling categories and profilers that are included in the Profiling build.

CategoryConfiguration nameTitle in HUDProfiler
Animations
Measures the time spent rendering animations.
MainLoopAnimationMain loop: animationm_animationProfiler
Application events handling
Measures the time spent gathering and handling events from all available event sources, such as keyboard, mouse, and other available manipulators.
MainLoopApplicationEventsMain loop: application eventsm_applicationEventsProfiler
Application logic updating
Measures the time spent inside the Application::update override that you provide.
MainLoopAppUpdateMain loop: application updatem_appUpdateProfiler
User-provided application logic updating
Measures the time spent executing the update logic callback Application::onUpdate that you provide.
MainLoopUserUpdateMain loop: user updatem_userUpdateProfiler
Graphics events handling
Measures the time spent processing events that affect graphics output, such as resizing a window.
MainLoopGraphicsEventsMain loop: graphics eventsm_graphicsEventsProfiler
Performance HUD
Measures the overhead caused by rendering the information in the Performance HUD.
MainLoopHUDMain loop: HUDm_hudProfiler
Input events handling
Measures the time that the InputManager spends processing input events, such as keyboard and mouse events.
MainLoopInputMain loop: inputm_inputProfiler
Layout
Measures the performance of the layout pass.
MainLoopLayoutMain loop: layoutm_layoutProfiler
Rendering
Measures the time spent rendering the screen in Application::renderOverride.
MainLoopRenderingMain loop: renderingm_renderingProfiler
Resource deployment
Measures the time spent processing the asynchronous task deployment queue.
MainLoopResourceDeploymentMain loop: resource deploymentm_resourceDeploymentProfiler
Resource manager update
Measures the time that the ResourceManager spends processing load and deployment queues.
MainLoopResourceManagerUpdateMain loop: resource manager updatem_resourceManagerUpdateProfiler
Task dispatcher
Measures the time spent executing tasks added to the task scheduler.
MainLoopTaskDispatcherMain loop: task dispatcherm_taskDispatcherProfiler
Task scheduler
Measures the time spent executing periodic tasks added to the task dispatcher, such as animations.
MainLoopTaskSchedulerMain loop: task schedulerm_taskSchedulerProfiler

MainLoopProfilingSampleBufferCount

You can set the sample buffer size in the main loop performance profilers that are included in the Profiling build. See Measuring the performance of Kanzi Engine and ProfilingCategoryFilter.

In application.cfg MainLoopProfilingSampleBufferCount = samples
In onConfigure() configuration.mainLoopProfilingSampleBufferCount = samples
Values
samples Maximum number of samples in the buffer for the main loop performance profilers included in the Kanzi Profiling build. The default value is 1024.
application.cfg example
# Sets the maximum number of samples in main loop performance profilers to 3600.
MainLoopProfilingSampleBufferCount = 3600
onConfigure() example
// Sets the maximum number of samples in main loop performance profilers to 3600.
configuration.mainLoopProfilingSampleBufferCount = 3600;

Glyph cache texture size

When you use a Text Block Kanzi creates a glyph cache texture for every font and font size combination. You can set the height and width of glyph cache textures to adjust the size of the glyph cache texture either when it gets full, or to optimize the performance of your Kanzi application.

Because larger glyph cache textures use more VRAM, try different sizes before you set the final size . The upper limit of the glyph cache texture size depends on the GPU, but usually it is 2048 by 2048 pixels. The default size of the glyph cache texture is 512 by 512 pixels.

Kanzi applies the size of the glyph cache texture to all glyph cache textures.

In application.cfg GlyphCacheHeight = size
GlyphCacheWidth = size
In onConfigure() configuration.glyphCacheHeight = size;
configuration.glyphCacheWidth = size;
Values
size Size of the glyph cache texture in pixels. The default value is 512.
application.cfg example
# Sets the glyph cache texture height to 768, and width to 1024 pixels.
GlyphCacheHeight = 768
GlyphCacheWidth = 1024
onConfigure() example
// Sets the glyph cache texture height to 768, and width to 1024 pixels.
configuration.glyphCacheHeight = 768;
configuration.glyphCacheWidth = 1024;

Optimization

Graphics initialization

On the integrity_rcar_rwm_aarch64 platform you can set whether you want to initialize the application graphics. Use this approach only as a late-stage optimization when you want to manually synchronize the starting of multiple applications that initialize at the same time.

This configuration controls the initialization of the graphics driver, device window manager, and whether the display is switched on. When you disable this configuration, to enable your Kanzi application to create a window, in the same process you must initialize:

When you disable graphics initialization with this configuration, you must initialize graphics for each application separately where you disabled this setting.

In application.cfg InitializePlatform = value
In onConfigure() configuration.defaultWindowProperties.initializePlatform = value;
Values
0 Disable the graphics initialization.
1 Enable the graphics initialization. Default value.
application.cfg example
# Disables the graphics initialization.
InitializePlatform = 0
onConfigure() example
// Disables the graphics initialization.
configuration.defaultWindowProperties.initializePlatform = 0;

Graphics card selection

On the platforms that use the GBM windowing system you can set which graphics card you want your Kanzi application to use.

In application.cfg DeviceIdentifier = identifier
In onConfigure() configuration.defaultDesktopProperties.deviceIdentifier = identifier;
Value
identifier Identifier of the graphics card that you want your Kanzi application to use. Default value for GBM is /dev/dri/card0.
application.cfg example
# Sets Kanzi to use the graphics card at /dev/dri/card1.
DeviceIdentifier = /dev/dri/card1
onConfigure() example
// Sets Kanzi to use the graphics card at /dev/dri/card1.
configuration.defaultDesktopProperties.deviceIdentifier = "/dev/dri/card1";

Graphics performance logging

GraphicsLoggingEnabled

You can enable Kanzi to print to the debug console the graphics API calls of your application in the Application::onConfigure() function, in the application.cfg, or using the command line argument, if your target supports command line arguments.

On the command line use:

In application.cfg GraphicsLoggingEnabled = value
In onConfigure() configuration.graphicsLoggingEnabled = value;
Values
0 Disable the logging of the graphics API calls. Default value.
1 Enable the logging of the graphics API calls.
application.cfg example
# Enables the logging of the graphics API calls.
GraphicsLoggingEnabled = 1
onConfigure() example
// Enables the logging of the graphics API calls.
configuration.graphicsLoggingEnabled = 1;

LogOpenGLExtensions

You can enable Kanzi to print to the debug console a list of the graphics-related extensions on application startup. To get this information when running your application on an Android device, in the application code use the logExtensions() function.

In application.cfg LogOpenGLExtensions = value
In onConfigure() configuration.extensionOutputEnabled = value;
Values
0 Disable the logging of the graphics-related extensions. Default value.
1 Enable the logging of the graphics-related extensions.
application.cfg example
# Enables the logging of the graphics-related extensions.
LogOpenGLExtensions = 1
onConfigure() example
// Enables the logging of the graphics-related extensions.
configuration.extensionOutputEnabled = 1;

LogOpenGLInformation

You can enable Kanzi to print to the debug console this graphics-related information on application startup:

To get this information when running your application on an Android device, in the application code use the logOpenGLInformation() function.

In application.cfg LogOpenGLInformation = value
In onConfigure() configuration.informationOutputEnabled = value;
Values
0 Disable the logging of the graphics-related information. Default value.
1 Enable the logging of the graphics-related information.
application.cfg example
# Enables the logging of the graphics-related information.
LogOpenGLInformation = 1
onConfigure() example
// Enables the logging of the graphics-related information.
configuration.informationOutputEnabled= 1;

LogSurfaceInformation

You can enable Kanzi to print to the debug console these graphics-related properties on application startup:

In application.cfg LogSurfaceInformation = value
In onConfigure() configuration.propertyOutputEnabled = value;
Values
0 Disable the logging of the graphics-related properties. Default value.
1 Enable the logging of the graphics-related properties.
application.cfg example
# Enables the logging of the graphics-related properties.
LogSurfaceInformation = 1
onConfigure() example
// Enables the logging of the graphics-related properties.
configuration.propertyOutputEnabled= 1;

Graphics library

On the Windows operating system you can select whether you want to use OpenGL ES or OpenGL in the Application::onConfigure() function, in the application.cfg, or using the command line arguments, if your target supports command line arguments.

On the command line use:

In application.cfg GraphicsBackend = type
In onConfigure() configuration.defaultSurfaceProperties.type = type;
configuration.defaultSurfaceProperties.contextApi = contextAPI;
Values
type

To use OpenGL ES and set the graphics context to EGL:

To use OpenGL and set the graphics context to WGL:

contextAPI

To use WGL, in onConfigure() use KZS_GRAPHICS_CONTEXT_API_WGL.

To use EGL, in onConfigure() use KZS_GRAPHICS_CONTEXT_API_EGL.

To use GLX, in onConfigure() use KZS_GRAPHICS_CONTEXT_API_GLX.

application.cfg example
# Sets the surface target for OpenGL rendering and WGL graphics context.
GraphicsBackend = opengl
onConfigure() example
// Sets the surface target for OpenGL rendering and WGL graphics context.
configuration.defaultSurfaceProperties.type = KZS_SURFACE_TYPE_GL_ONLY;

Surface properties

Surface properties control the properties of the hardware accelerated graphics surface on which Kanzi renders. They control the relation between image quality and rendering speed. The surface properties you set are considered requests to be matched by the graphics system of the target hardware. Whether a given request is considered an upper bound, a lower bound, or an exact value is platform dependent.

The default values of surface properties are platform dependent. You can get them by calling kzsSurfaceGetDefaultProperties().

In application.cfg

SurfaceBitsStencil = stencil
SurfaceBitsDepthBuffer = buffer
SurfaceBitsRed = red
SurfaceBitsGreen = green
SurfaceBitsBlue = blue
SurfaceBitsAlpha = alpha
SurfaceBitsPadding = padding
SurfaceSamplesAntialiasing = anti
SwapBehavior = swap

In onConfigure() configuration.defaultSurfaceProperties.bitsStencil = stencil;
configuration.defaultSurfaceProperties.bitsDepthBuffer = buffer;
configuration.defaultSurfaceProperties.bitsColorR = red;
configuration.defaultSurfaceProperties.bitsColorG = green;
configuration.defaultSurfaceProperties.bitsColorB = blue;
configuration.defaultSurfaceProperties.bitsAlpha = alpha;
configuration.defaultSurfaceProperties.bitsPadding = padding;
configuration.defaultSurfaceProperties.antiAliasing = anti;
configuration.defaultSurfaceProperties.swapBehaviorCopy = swap;
configuration.defaultSurfaceProperties.priority = priority;
Values
stencil Size of the stencil buffer in bits.
buffer Size of the depth buffer in bits.
red Size of the red color channel in bits.
green Size of the green color channel in bits.
blue Size of the blue color channel in bits.
alpha Size of the alpha channel in bits.
padding Size of the padding in bits that is added to the application window.
Setting the padding size is supported only on the QNX operating system.
anti Number of anti-aliasing samples used. The default value is 0.
By default, the Kanzi Studio Preview and the Kanzi Application Player on Windows apply anti-aliasing using four samples. For both you can configure the amount of anti-aliasing that you want to use. See Setting anti-aliasing in the Preview and Application Player.
swap During the swap buffer, are the buffers swapped or copied. Use 1 for copy, 0 for swap, KZS_SURFACE_PROPERTY_DONT_CARE for automatic selection. Default value is 0 (swap).
priority Enables the creation of EGL content with a priority hint. The default value is KZS_SURFACE_PROPERTY_DONT_CARE, which does not apply the priority. You can set the priority only in the onConfigure() function.
application.cfg example

# An example configuration for a typical high-speed rendering application.
SurfaceBitsStencil = 1
SurfaceBitsDepthBuffer = 16
SurfaceBitsRed = 5
SurfaceBitsGreen = 6
SurfaceBitsBlue = 5
SurfaceBitsAlpha = 0
SurfaceSamplesAntialiasing = 0

# An example configuration for a high image quality application.
SurfaceBitsStencil = 8
SurfaceBitsDepthBuffer = 24
SurfaceBitsRed = 8
SurfaceBitsGreen = 8
SurfaceBitsBlue = 8
SurfaceBitsAlpha = 8
SurfaceSamplesAntialiasing = 4

# Create on Linux GBM DRM windowing system a 32-bit surface with alpha (GBM_FORMAT_ARGB8888).
SurfaceBitsRed = 8
SurfaceBitsGreen = 8
SurfaceBitsBlue = 8
SurfaceBitsAlpha = 8

# Create on Linux GBM DRM windowing system a 32-bit surface without alpha,
# 24-bit color depth, and 8-bit padding (GBM_FORMAT_XRGB8888).
SurfaceBitsRed = 8
SurfaceBitsGreen = 8
SurfaceBitsBlue = 8
SurfaceBitsAlpha = 0 SurfaceBitsPadding = 8

onConfigure() example

// An example configuration for a typical high-speed rendering application.
configuration.defaultSurfaceProperties.bitsStencil = 1;
configuration.defaultSurfaceProperties.bitsDepthBuffer = 16;
configuration.defaultSurfaceProperties.bitsColorR = 5;
configuration.defaultSurfaceProperties.bitsColorG = 6;
configuration.defaultSurfaceProperties.bitsColorB = 5;
configuration.defaultSurfaceProperties.bitsAlpha = 0;
configuration.defaultSurfaceProperties.antiAliasing = 0;

// An example configuration for a high image quality application.
configuration.defaultSurfaceProperties.bitsStencil = 8;
configuration.defaultSurfaceProperties.bitsDepthBuffer = 24;
configuration.defaultSurfaceProperties.bitsColorR = 8;
configuration.defaultSurfaceProperties.bitsColorG = 8;
configuration.defaultSurfaceProperties.bitsColorB = 8;
configuration.defaultSurfaceProperties.bitsAlpha = 8;
configuration.defaultSurfaceProperties.antiAliasing = 4;

// Create on Linux GBM DRM windowing system a 32-bit surface with alpha (GBM_FORMAT_ARGB8888).
configuration.defaultSurfaceProperties.bitsColorR = 8;
configuration.defaultSurfaceProperties.bitsColorG = 8;
configuration.defaultSurfaceProperties.bitsColorB = 8;
configuration.defaultSurfaceProperties.bitsAlpha = 8;

// Create on Linux GBM DRM windowing system a 32-bit surface without alpha,
// 24-bit color depth, and 8-bit padding (GBM_FORMAT_XRGB8888).
configuration.defaultSurfaceProperties.bitsColorR = 8;
configuration.defaultSurfaceProperties.bitsColorG = 8;
configuration.defaultSurfaceProperties.bitsColorB = 8;
configuration.defaultSurfaceProperties.bitsAlpha = 0; configuration.defaultSurfaceProperties.bitsPadding = 8;

Application window position and size

You can set the position of your Kanzi application on the screen relative to the upper-left corner of the screen and the size of the application window in pixels. The default size of the window is 640x480 pixels and center of the device screen.

To make the application window fixed size, resizable, fullscreen, or without borders, see WindowStyle.

To set the default display where the application window appears, see DefaultDisplayIndex.

In application.cfg WindowX = positionX
WindowY = positionY
WindowWidth = width
WindowHeight = height
WindowOrder = order
In onConfigure() configuration.defaultWindowProperties.x = positionX;
configuration.defaultWindowProperties.y = positionY;
configuration.defaultWindowProperties.width = width;
configuration.defaultWindowProperties.height = height;
configuration.defaultWindowProperties.order = order;
Value
positionX Horizontal position of the top-left corner of the application window from the top-left corner of the screen in pixels. Use 0 to position the window to the left of the device screen.
positionY Vertical position of the top-left corner of the application window from the top-left corner of the screen in pixels. Use 0 to position the window to the top of the device screen.
width Window width in pixels.
height Window height in pixels.
order Z-order of the application window. The value is target platform dependent. The default value is NativeWindowProperties::WindowPositionUnspecified, which does not apply the order.
application.cfg example
# Set the width to 1280 and height to 720 pixels and place it 100 pixels
# from the top and 1 pixel from the left side of the device screen.
WindowWidth = 1280
WindowHeight = 720
WindowX = 100
WindowY = 1
# Place the application window in the top-left corner of the device screen.
WindowX = 0
WindowY = 0
# On Windows, places the application window on top of other windows.
WindowOrder = 0
onConfigure() example
// Set the width to 1280 and height to 720 pixels and place it 100 pixels
// from the top and 1 pixel from the left side of the device screen.
configuration.defaultWindowProperties.width = 1280;
configuration.defaultWindowProperties.height = 720; configuration.defaultWindowProperties.x = 100; configuration.defaultWindowProperties.y = 1;
// Place the application window in the top-left corner of the device screen.
configuration.defaultWindowProperties.x = 0;
configuration.defaultWindowProperties.y = 0;
// On Windows, places the application window on top of other windows.
configuration.defaultWindowProperties.order = 0;

Application window configuration

WindowStyle

You can set the style of your Kanzi application window. Besides the default window with a border that users can resize, you can set your Kanzi application to launch in a window without a border, in a window of fixed size, and in a window that occupies the entire device screen.

To set the position and size of the application window, see Application window position and size.

In application.cfg WindowStyle = "style"
In onConfigure() configuration.defaultWindowProperties.style = style;
Value
style

To set a window without borders or any other decorations that users cannot resize:

To set a window that users cannot resize:

To set a window that occupies the whole device screen:

To set a window that users can resize:

application.cfg example

# Launch the application in a window that occupies the whole screen of the device.
WindowStyle = "fullscreen"

onConfigure() example
// Launch the application in a window that occupies the whole screen of the device.
configuration.defaultWindowProperties.style = KZS_WINDOW_STYLE_FULL_SCREEN;

DefaultDisplayIndex

When you run your Kanzi application in full-screen mode on a system with more than one display, you can set the default display where your Kanzi application window appears.

To make the application window fullscreen, see WindowStyle.

In application.cfg DefaultDisplayIndex = index
In onConfigure() configuration.defaultWindowProperties.defaultDisplayIndex = index;
Value
index Index number of the display. Default value is 0.
application.cfg example
# Sets the second display as the default display for the full-screen application window.
DefaultDisplayIndex = 1
onConfigure() example
// Sets the second display as the default display for the full-screen application window.
configuration.defaultWindowProperties.defaultDisplayIndex = 1;

WindowBufferCount

If the windowing system of your target device supports setting the number of window buffers, you can set the number of native window buffers that your Kanzi application window uses. For example, Renesas window manager and QNX Screen support the setting of the number of window buffers.

In application.cfg WindowBufferCount = value
In onConfigure() configuration.defaultWindowProperties.bufferCount = value;
Values
value The number of native window buffers used by the Kanzi application window. The default value is 0 and sets Kanzi to use the default value provided by the native windowing system of the target device.
application.cfg example

# Set the number of native window buffers used by the Kanzi application window to 3.
WindowBufferCount = 3

onConfigure() example
// Set the number of native window buffers used by the Kanzi application window to 3.
configuration.defaultWindowProperties.bufferCount = 3;

Input handling

You can define how your application handles touch and pointer input. When you run your application on a device, you can set whether the application reacts to the pointer of the device, uses a touch screen, or both. You can also set the transformation matrix of the input event coordinates.

InputTransform

You can set the transformation matrix of the input event coordinates. This transformation only affects input event coordinates, not the orientation of the Kanzi application screen. For example, use this to rotate the touch screen in relation to your application screen.

In application.cfg InputTransform = transformation
In onConfigure() configuration.defaultEventSourceProperties.transformation = transformation;
Values
transformation Transformation matrix of the touch screen.
application.cfg example

# Rotate a touch screen sized 1280x720 pixels by 180 degrees.
InputTransform = -1, 0, 0, 0, -1, 0, 1280, 720, 1

onConfigure() example
// Rotate a touch screen sized 1280x720 pixels by 180 degrees.
configuration.defaultEventSourceProperties.transformation = Matrix3x3::createTranslation(1280, 720) * Matrix3x3::createRotationInDegrees(180.0f);
 

The examples use this equation to calculate the transformation matrix:

InputTranslation

You can set how Kanzi translates pointer and touch events.

In application.cfg InputTranslation = translation
In onConfigure() configuration.defaultEventSourceProperties.translation = translation;
Values
translation

Translation of pointer and touch events.

To not apply any translation:

To translate pointer events to touch events:

To translate pointer events to touch events, and preserve pointer events:

To translate touch events to pointer events:

To translate touch events to pointer events, and preserve touch events:

application.cfg example

# Translate pointer events to touch events.
InputTranslation = PointerToTouch

onConfigure() example
// Translate pointer events to touch events.
configuration.defaultEventSourceProperties.translation = KZS_INPUT_TRANSLATE_POINTER_TO_TOUCH;

InputDiscardPointer

You can set whether the application reacts to the pointer of the device.

In application.cfg InputDiscardPointer = value
In onConfigure() configuration.defaultEventSourceProperties.discardPointerEvents = value;
Values
value
0 Do not ignore pointer input. Default value.
1 Ignore pointer input.
application.cfg example

# Ignore pointer input.
InputDiscardPointer = 1

onConfigure() example
// Ignore pointer input.
configuration.defaultEventSourceProperties.discardPointerEvents = 1;

InputDiscardTouch

You can set whether the application reacts to touch input.

In application.cfg InputDiscardTouch = value
In onConfigure() configuration.defaultEventSourceProperties.discardTouchEvents = value;
Values
value
0 Do not ignore touch input. Default value.
1 Ignore touch input.
application.cfg example

# Ignore touch input.
InputDiscardTouch = 1

onConfigure() example
// Ignore touch input.
configuration.defaultEventSourceProperties.discardTouchEvents = 1;

Input event devices on Linux

You can configure the input event devices that Kanzi listens to on Linux ports where the native windowing system does not provide input device handling. This way Kanzi can listen to events directly from the input event devices provided by the operating system.
For example, in Vivante fbdev and WSEGL ports you can configure the input event devices that Kanzi listens to. In X11 and Wayland ports the native windowing system handles input devices.

Kanzi by default listens to all input event devices named eventN, where N is an integer, in the /dev/input directory.

In application.cfg InputEventDevice = path
In onConfigure() configuration.defaultEventSourceProperties.inputEventDevice = path;
Values
path Full path to one or more input event devices. Separate a list of several paths with a semicolon.
application.cfg example
# Listens to events from one input event device.
InputEventDevice = "/dev/input/event1"
# Listens to events from two input event devices.
InputEventDevice = "/dev/input/event0;/dev/input/event1"
# Disables listening to events from input event devices.
InputEventDevice = "none"
onConfigure() example
// Listens to events from one input event device.
configuration.defaultEventSourceProperties.inputEventDevice = "/dev/input/event1";
// Listens to events from two input event devices.
configuration.defaultEventSourceProperties.inputEventDevice = "/dev/input/event0;/dev/input/event1";
// Disables listening to events from input event devices.
configuration.defaultEventSourceProperties.inputEventDevice = "none";

See also

Configuring your application

Best practices

Loading resources in parallel

Using kzb files